@bendyline/squisq-editor-react 2.1.0 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bendyline LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,40 @@
+# Third-Party Notices for @bendyline/squisq-editor-react
+
+This notice applies to the `@bendyline/squisq-editor-react` npm package.
+Squisq-authored code is licensed under the MIT license in `LICENSE`.
+Third-party components remain under their respective license terms.
+
+## Runtime and peer dependencies
+
+| Package                        | Version   | License                       | Repository                                   |
+| ------------------------------ | --------- | ----------------------------- | -------------------------------------------- |
+| @bendyline/squisq              | 2.1.0     | MIT                           | https://github.com/bendyline/squisq          |
+| @bendyline/squisq-formats      | 2.1.0     | MIT                           | https://github.com/bendyline/squisq          |
+| @bendyline/squisq-react        | 2.1.0     | MIT                           | https://github.com/bendyline/squisq          |
+| @fortawesome/fontawesome-free  | 7.2.0     | CC-BY-4.0 AND OFL-1.1 AND MIT | https://github.com/FortAwesome/Font-Awesome  |
+| @monaco-editor/react           | 4.7.0     | MIT                           | https://github.com/suren-atoyan/monaco-react |
+| @tiptap/extension-image        | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-link         | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-mention      | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-placeholder  | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-table        | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-table-cell   | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-table-header | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-table-row    | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-task-item    | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/extension-task-list    | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/pm                     | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/react                  | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/starter-kit            | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| @tiptap/suggestion             | 2.27.2    | MIT                           | https://tiptap.dev                           |
+| mermaid                        | 11.16.0   | MIT                           | https://github.com/mermaid-js/mermaid        |
+| type-fest                      | 4.41.0    | MIT OR CC0-1.0                | https://github.com/sindresorhus/type-fest    |
+| monaco-editor _(peer)_         | >=0.50.0  | MIT                           | https://github.com/microsoft/monaco-editor   |
+| react _(peer)_                 | ^18 / ^19 | MIT                           | https://github.com/facebook/react            |
+| react-dom _(peer)_             | ^18 / ^19 | MIT                           | https://github.com/facebook/react            |
+
+Font Awesome Free contains icon artwork under CC-BY-4.0, font files under
+OFL-1.1, and CSS/JavaScript under MIT. Attribution is required when its icon
+artwork is redistributed. Mermaid is Copyright (c) 2014-2022 Knut Sveidqvist
+and is distributed under the MIT License. Complete license texts are included
+in the respective dependency distributions and source repositories.

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject, KeyboardEvent } from 'react';
 import { Doc, MediaProvider, Theme, CustomTemplateDefinition, ThemeSeedColors, ViewportPreset, ViewportConfig, Block, MediaEntry, DiagramEdgeAnchor, SurfaceScheme, ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
-import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { MarkdownDocument, ResourcePolicy } from '@bendyline/squisq/markdown';
 import { ContentContainer } from '@bendyline/squisq/storage';
 import { DocumentVersionManager, SaveVersionOptions, SaveVersionResult, PrunePolicy } from '@bendyline/squisq/versions';
 import * as _tiptap_core from '@tiptap/core';
@@ -365,6 +365,13 @@ interface EditorContextValue extends EditorState, EditorActions {
      * path link. When unset, the dialog falls back to URL-only.
      */
     documentLinkProvider: DocumentLinkProvider | null;
+    /**
+     * Extra link schemes the host intercepts itself (e.g. an app-internal
+     * navigation protocol). The link dialog validates against core's
+     * `sanitizeUrl` with these allowed, so authors aren't told a scheme the
+     * host DOES resolve is unsupported. Executable schemes stay refused.
+     */
+    linkSchemes: readonly string[] | undefined;
 }
 type ImageDisplayMode = 'inline' | 'thumbnail';
 /**
@@ -429,6 +436,12 @@ interface EditorProviderProps {
      * Omit to fall back to URL-only link insertion.
      */
     documentLinkProvider?: DocumentLinkProvider | null;
+    /**
+     * Extra link schemes this host resolves itself. Threaded into the link
+     * dialog's `sanitizeUrl` check so a host-custom protocol is accepted;
+     * executable schemes are refused regardless.
+     */
+    linkSchemes?: readonly string[];
     /**
      * Whether the in-editor media recorder is available in the toolbar.
      * Defaults to true. Set to false to suppress the recorder affordance
@@ -535,7 +548,7 @@ interface ViewPreferences {
     /** Document vs. block-at-a-time layout. */
     layoutMode?: LayoutMode;
 }
-declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, documentLinkProvider, allowRecording, allowNarrate, fileName, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, documentLinkProvider, linkSchemes, allowRecording, allowNarrate, fileName, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Host-supplied context sections rendered INSIDE the Monaco (raw/code)
@@ -714,6 +727,8 @@ interface EditorShellProps {
     toolbarSlotAfterActions?: ReactNode;
     /** Content rendered at the rightmost end of the toolbar, after all other elements. */
     toolbarSlotRight?: ReactNode;
+    /** Host-supplied content rendered at the right edge of the bottom status bar. */
+    statusBarSlotRight?: ReactNode;
     /**
      * Whether to show the "Play" (preview) tab in the toolbar. When false, the
      * tab and its preview panel are hidden, and ⌘3 becomes a no-op. Use this
@@ -770,8 +785,8 @@ interface EditorShellProps {
      */
     writeCanvasSettings?: WriteCanvasSettings;
     /**
-     * Render the bottom status bar (word / character / line / block counts
-     * and parse-state indicator). Defaults to `true`. Set to `false` in
+     * Render the bottom status bar (word / character / line / block counts,
+     * parse errors, and optional host status). Defaults to `true`. Set to `false` in
      * embedded surfaces — chat composers and other short-form inputs —
      * where the stats are noise.
      */
@@ -827,6 +842,14 @@ interface EditorShellProps {
      * remote API, …) implement this; the editor stays agnostic.
      */
     documentLinkProvider?: DocumentLinkProvider | null;
+    /**
+     * Extra link schemes this host resolves itself (e.g. an app-internal
+     * navigation protocol). The link dialog validates typed URLs against
+     * core's `sanitizeUrl` with these allowed, so an author isn't told a
+     * scheme the host DOES handle is unsupported. Executable schemes
+     * (`javascript:`, `vbscript:`, `data:`) are refused regardless.
+     */
+    linkSchemes?: readonly string[];
     /**
      * Whether the in-editor media recorder is surfaced in the toolbar.
      * Defaults to true — when a `mediaProvider` is wired, a record
@@ -969,7 +992,7 @@ interface EditorShellProps {
  * Complete markdown editor shell with toolbar, view switcher, and three
  * editing modes: Raw (Monaco), WYSIWYG (Tiptap), and Preview.
  */
-declare function EditorShell({ initialMarkdown, initialView, articleId, basePath, onChange, colorScheme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, showPlayTab, submitOnEnter, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, language, findMode, onFindModeChange, mentionProvider, documentLinkProvider, allowRecording, allowNarrate, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
+declare function EditorShell({ initialMarkdown, initialView, articleId, basePath, onChange, colorScheme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, statusBarSlotRight, showPlayTab, submitOnEnter, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, language, findMode, onFindModeChange, mentionProvider, documentLinkProvider, linkSchemes, allowRecording, allowNarrate, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Bridges a host-supplied {@link CodeContext} onto the live Monaco editor:
@@ -1727,6 +1750,13 @@ interface PreviewSettings {
     /** Config for the docked theme designer, or null when closed. Rendered by
      *  `<ThemeDesignerDock>` in the editor's content row. */
     themeDesigner: ThemeDesignerConfig | null;
+    /**
+     * Set when a theme write was ABORTED because the document source could not
+     * be read. The write is skipped rather than merged onto an empty list (which
+     * would erase the doc's other custom themes/templates), so this must be
+     * shown — otherwise the save looks like a silent no-op.
+     */
+    themeSaveError: string | null;
 }
 /** Everything `<ThemeDesignerDock>` needs to render the designer pane. */
 interface ThemeDesignerConfig {
@@ -2179,20 +2209,17 @@ interface MediaBinProps {
 }
 declare function MediaBin({ mediaProvider, isDark, refreshKey, usedMediaPaths, onMediaUploaded, onMediaRemoved, onCountChange, }: MediaBinProps): react_jsx_runtime.JSX.Element;
 
-/**
- * StatusBar
- *
- * Bottom status bar showing document statistics and parse status.
- */
 interface StatusBarProps {
     /** Additional class name */
     className?: string;
+    /** Host-supplied status content rendered at the right edge. */
+    slotRight?: ReactNode;
 }
 /**
  * Status bar displaying document statistics: character count, word count,
- * block count, and parse/error status.
+ * block count, parse errors, and optional host status.
  */
-declare function StatusBar({ className }: StatusBarProps): react_jsx_runtime.JSX.Element;
+declare function StatusBar({ className, slotRight }: StatusBarProps): react_jsx_runtime.JSX.Element;
 
 /**
  * TooltipLayer
@@ -2637,6 +2664,27 @@ interface DiagramCanvasProps {
 }
 declare function DiagramCanvas({ nodes: incomingNodes, edges: incomingEdges, onCommand, showMaximize, maximized, onToggleMaximize, activeToolId: controlledToolId, onActiveToolIdChange, onSelectionChange, textChannel, }: DiagramCanvasProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Shared position-registry remapping for the fence-widget families (ascii
+ * diagram, tree, timeline, mermaid, repairable).
+ *
+ * Each family keeps a registry of `{ id, pos }` entries: a synthetic session
+ * id per claimed code fence, plus that fence's current document position.
+ * The id is what keys the widget decoration, so preserving it across a
+ * transaction is what keeps the mounted React root — and all of its
+ * unpersisted state (pan/zoom, height, `sourceVisible`, collapse set) —
+ * alive. This module owns the one rule for deciding which old id belongs to
+ * which new position; it lived as five near-identical copies before.
+ */
+
+/** One registered fence: a stable session id at a live document position. */
+interface FenceBlockEntry {
+    /** Synthetic session id, stable across edits to one fence. */
+    id: string;
+    /** Document position of the codeBlock node at the current state. */
+    pos: number;
+}
+
 /**
  * AsciiDiagramExtension — Tiptap/ProseMirror plugin that turns code blocks
  * containing ASCII box-and-line diagrams into interactive diagram canvases.
@@ -2663,12 +2711,7 @@ declare function DiagramCanvas({ nodes: incomingNodes, edges: incomingEdges, onC
  * doesn't kick the user back to a raw code block mid-edit.
  */
 
-interface AsciiDiagramBlockEntry {
-    /** Synthetic session id (`ascii-N`), stable across edits for one block. */
-    id: string;
-    /** Document position of the codeBlock node at the current state. */
-    pos: number;
-}
+type AsciiDiagramBlockEntry = FenceBlockEntry;
 interface AsciiDiagramPluginState {
     entries: AsciiDiagramBlockEntry[];
     decorations: DecorationSet;
@@ -2759,6 +2802,12 @@ interface ApplyAsciiDiagramCommandOptions {
  * is re-recognized even after it's flattened. No-op (returns false) only when
  * BOTH the text is already identical AND the language already matches, so
  * history stays clean on a true no-op.
+ *
+ * This is the single write boundary for the diagram, tree AND timeline
+ * families, so it is also where the editor's read-only authority is enforced.
+ * A mounted canvas/outline outlives the render that created its controls, so
+ * a host flipping the editor read-only (saving, locked, permission change)
+ * must not leave a stale drag/click able to rewrite the fence.
  */
 declare function replaceAsciiFenceText(editor: Editor$1, pos: number, nextText: string, ensureLanguage?: string): boolean;
 /**
@@ -2790,12 +2839,7 @@ declare function applyAsciiDiagramCommand(editor: Editor$1, blockId: string, cmd
  * mapping so the button always resolves the right fence.
  */
 
-interface RepairableBlockEntry {
-    /** Synthetic session id (`repair-N`), stable across edits for one block. */
-    id: string;
-    /** Document position of the codeBlock node at the current state. */
-    pos: number;
-}
+type RepairableBlockEntry = FenceBlockEntry;
 interface RepairablePluginState {
     entries: RepairableBlockEntry[];
     decorations: DecorationSet;
@@ -2889,12 +2933,7 @@ declare function shouldPasteAsAsciiFence(text: string): boolean;
  * model. That keeps every Mermaid diagram type and directive round-trippable.
  */
 
-interface MermaidDiagramBlockEntry {
-    /** Synthetic session id, stable while this code block remains in the doc. */
-    id: string;
-    /** Current ProseMirror position of the `codeBlock`. */
-    pos: number;
-}
+type MermaidDiagramBlockEntry = FenceBlockEntry;
 interface MermaidDiagramPluginState {
     entries: MermaidDiagramBlockEntry[];
     decorations: DecorationSet;
@@ -3170,12 +3209,40 @@ declare function isMermaidFlowchartShapeId(value: string): value is MermaidFlowc
 declare function normalizeMermaidFlowchartShape(value: string | null | undefined): MermaidFlowchartShapeId;
 
 type MermaidFlowchartDirection = 'TB' | 'TD' | 'BT' | 'RL' | 'LR';
+type MermaidEditableDiagramKind = 'flowchart' | 'sequence' | 'state' | 'class' | 'er' | 'mindmap' | 'c4' | 'architecture' | 'gantt' | 'timeline' | 'journey' | 'kanban' | 'git' | 'pie' | 'quadrant' | 'sankey' | 'xy' | 'requirement';
+interface MermaidEditCapabilities {
+    readonly addNode: boolean;
+    readonly renameNode: boolean;
+    readonly duplicateNode: boolean;
+    readonly deleteNode: boolean;
+    readonly connect: boolean;
+    readonly disconnect: boolean;
+    readonly edgeLabel: boolean;
+    readonly shape: boolean;
+    readonly direction: boolean;
+    readonly properties: boolean;
+    /** Explains why Connect is intentionally absent for ordered/data grammars. */
+    readonly connectionHint?: string;
+}
+interface MermaidDiagramProperty {
+    readonly id: string;
+    readonly label: string;
+    readonly value: string | boolean;
+    readonly type?: 'text' | 'boolean' | 'select';
+    readonly options?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly placeholder?: string;
+}
 interface MermaidEditableNode {
     id: string;
     domId: string;
     label: string;
     shape: MermaidFlowchartShapeId;
     classes: readonly string[];
+    /** Source adapter metadata. Never serialized into the Mermaid SVG. */
+    origin?: Readonly<Record<string, string | number | boolean>>;
 }
 interface MermaidEditableEdge {
     id: string;
@@ -3185,6 +3252,8 @@ interface MermaidEditableEdge {
     type?: string;
     stroke?: string;
     userDefinedId?: boolean;
+    /** Source adapter metadata. Never serialized into the Mermaid SVG. */
+    origin?: Readonly<Record<string, string | number | boolean>>;
 }
 interface MermaidFlowchartModel {
     kind: 'flowchart';
@@ -3192,8 +3261,20 @@ interface MermaidFlowchartModel {
     nodes: readonly MermaidEditableNode[];
     edges: readonly MermaidEditableEdge[];
 }
+interface MermaidSourceEditableModel {
+    kind: Exclude<MermaidEditableDiagramKind, 'flowchart'>;
+    nodes: readonly MermaidEditableNode[];
+    edges: readonly MermaidEditableEdge[];
+    capabilities: MermaidEditCapabilities;
+    properties: readonly MermaidDiagramProperty[];
+    nodeNoun: string;
+    edgeNoun: string;
+    direction?: MermaidFlowchartDirection;
+}
 /** Structured editing is additive to full Mermaid rendering, never required by it. */
-type MermaidEditableModel = MermaidFlowchartModel;
+type MermaidEditableModel = MermaidFlowchartModel | MermaidSourceEditableModel;
+declare function mermaidEditCapabilities(model: MermaidEditableModel): MermaidEditCapabilities;
+declare function mermaidDiagramProperties(model: MermaidEditableModel): readonly MermaidDiagramProperty[];
 
 type MermaidNodeCanvasAction = 'rename' | 'shape' | 'duplicate' | 'connect' | 'delete';
 interface MermaidDiagramCanvasProps {
@@ -3359,12 +3440,7 @@ declare function codeSnippetMarkdown(language: string, source: string): string;
  * extension claims any given fence.
  */
 
-interface TreeBlockEntry {
-    /** Synthetic session id (`tree-N`), stable across edits for one block. */
-    id: string;
-    /** Document position of the codeBlock node at the current state. */
-    pos: number;
-}
+type TreeBlockEntry = FenceBlockEntry;
 interface TreeViewPluginState {
     entries: TreeBlockEntry[];
     decorations: DecorationSet;
@@ -3488,12 +3564,7 @@ declare function shouldPasteAsTreeFence(text: string): boolean;
  * truth. Every semantic edit is rendered back through the core codec.
  */
 
-interface TimelineBlockEntry {
-    /** Synthetic session id, stable across edits to one fence. */
-    id: string;
-    /** Current document position of the codeBlock node. */
-    pos: number;
-}
+type TimelineBlockEntry = FenceBlockEntry;
 interface TimelineViewPluginState {
     entries: TimelineBlockEntry[];
     decorations: DecorationSet;
@@ -3990,10 +4061,17 @@ interface ScreenStreamOptions {
 /**
  * Handle returned by {@link requestScreenStream}. The `stream` is what
  * gets handed to `MediaRecorder`; the `dispose()` callback shuts down
- * any auxiliary resources (e.g. the mic-mix `AudioContext`). Callers
- * must also stop the stream's tracks via `stream.getTracks().forEach(t
- * => t.stop())` when done — `dispose()` cleans up everything that isn't
- * the stream itself.
+ * any auxiliary resources (the mic-mix `AudioContext` plus the raw
+ * source tracks feeding it). Callers must also stop the stream's tracks
+ * via `stream.getTracks().forEach(t => t.stop())` when done —
+ * `dispose()` cleans up everything that isn't the stream itself.
+ *
+ * IMPORTANT for callers: when the microphone is mixed in, the raw
+ * system-audio / mic tracks are deliberately NOT members of `stream`
+ * (only the single mixed output track is). So stopping `stream`'s tracks
+ * alone leaves those captures live — `dispose()` is what releases them,
+ * and it must always be called alongside the stream teardown or the
+ * screen-share indicator stays lit.
  */
 interface ScreenStreamHandle {
     stream: MediaStream;
@@ -4217,22 +4295,47 @@ declare function buildNarrationSavePlan(args: NarrationSavePlanArgs): NarrationS
 interface ExecuteNarrationSaveDeps {
     mediaProvider: MediaProvider;
     container: ContentContainer | null;
-    markdownSource: string;
+    /**
+     * Read the LIVE markdown source at write time. Deliberately a getter, not
+     * a snapshot: the media writes above are async, and a value captured before
+     * them would compose the preamble from a stale source and clobber anything
+     * that landed in between.
+     */
+    getMarkdownSource: () => string;
     setMarkdownSource: (next: string) => void;
     bumpMediaRevision: () => void;
 }
+/**
+ * What a save attempt has already committed. Passed back in on a retry so a
+ * second attempt REUSES the audio it already wrote instead of writing another
+ * timestamped file (and orphaning the first).
+ *
+ * Mutated in place by {@link executeNarrationSave} as each step lands, which
+ * is what makes the record survive the throw that aborted the attempt.
+ */
+interface NarrationSaveProgress {
+    audioPath?: string;
+    cameraPath?: string | null;
+    sidecarPath?: string;
+}
 interface NarrationSaveResult {
     audioPath: string;
     cameraPath: string | null;
     sidecarPath: string;
 }
-/** Execute a save plan: media writes, sidecar, then the single markdown write. */
+/**
+ * Execute a save plan: media writes, sidecar, then the single markdown write.
+ *
+ * Every step is idempotent against `progress`. A failed attempt leaves its
+ * completed steps recorded there, so retrying with the SAME progress object
+ * resumes rather than restarts — no duplicate audio, no second sidecar.
+ */
 declare function executeNarrationSave(plan: NarrationSavePlan, take: {
     audioBlob: Blob;
     audioMime: string;
     cameraBlob: Blob | null;
     cameraMime: string | null;
-}, deps: ExecuteNarrationSaveDeps): Promise<NarrationSaveResult>;
+}, deps: ExecuteNarrationSaveDeps, progress?: NarrationSaveProgress): Promise<NarrationSaveResult>;
 
 /**
  * Pure markdown edit: insert (or replace) the narration reference at the
@@ -4241,12 +4344,40 @@ declare function executeNarrationSave(plan: NarrationSavePlan, take: {
  * The narration take is referenced by a preamble media annotation —
  * `{[audio src=audio/narration-….webm anchor=document]}` — the canonical
  * authored form `markdownToDoc` lifts into `doc.documentMedia`. A prior
- * teleprompter take's line (matched by the `audio/narration-` prefix +
- * `anchor=document`) is replaced, so retakes swap the reference instead
- * of stacking narrations. The optional camera companion rides on the
- * next line as an inline `<video>` (deliberately NOT doc-anchored:
+ * teleprompter take's line is replaced, so retakes swap the reference
+ * instead of stacking narrations. The optional camera companion rides on
+ * the next line as an inline `<video>` (deliberately NOT doc-anchored:
  * document-anchored video renders full-bleed behind every block and is
  * excluded from export audio — not a talking head).
+ *
+ * ## Matching a prior take by ROLE, not by path
+ *
+ * These patterns deliberately do not encode a `audio/narration-` /
+ * `video/narration-cam-` path prefix. `narrationSave` treats the path
+ * RETURNED by `MediaProvider.addMedia` as authoritative because providers
+ * may rename or relocate the file, so a path-shaped matcher misses the
+ * very annotation it wrote and the next retake stacks a second one — two
+ * document-anchored audio tracks playing at once.
+ *
+ * Instead we match the annotation's ROLE, scoped to POSITION:
+ *
+ * - Narration: a `{[audio … anchor=document …]}` line. Document-anchored
+ *   audio is a single-occupancy slot (it becomes `doc.documentMedia` and
+ *   is what `applyNarrationTiming` / `resolveAudioMapping` treat as *the*
+ *   narration), so replacing whatever occupies it is exactly right —
+ *   two of them is never a valid document.
+ * - Camera: a `<video …></video>` line sitting immediately after that
+ *   narration line (blank lines allowed between). Adjacency to the
+ *   preamble is the role marker here — an inline `<video>` carries no
+ *   anchor of its own, and this is the exact shape `cameraVideoLine`
+ *   emits as part of the same insert.
+ *
+ * Both matchers are confined to the PREAMBLE REGION — the blank-padded run
+ * at the insertion point (top of file, or just after the frontmatter fence).
+ * Role alone is not enough: matching document-wide would let a retake
+ * silently replace a background-music annotation the user wrote further
+ * down, or consume whichever `<video>` of theirs happened to follow it.
+ * Content outside the region we wrote is never touched.
  */
 declare function narrationAnnotationLine(audioPath: string): string;
 declare function cameraVideoLine(cameraPath: string): string;
@@ -4652,6 +4783,8 @@ interface UseImageEditorOptions {
      * `assets/source.<ext>` so the doc is portable.
      */
     initialSrc?: string;
+    /** Policy and byte/time limits for fetching `initialSrc`. */
+    resourcePolicy?: ResourcePolicy;
     /** Override the state filename. Defaults to `state.json`. */
     stateFilename?: string;
     /** Enable version history. Default: `false`. */
@@ -4685,4 +4818,4 @@ interface UseImageEditorReturn {
 }
 declare function useImageEditor(options: UseImageEditorOptions): UseImageEditorReturn;
 
-export { ALL_PICKER_ENTRIES, type AddTimelineEventOptions, type AddTimelineEventResult, type ApplyAsciiDiagramCommandOptions, type AsciiDiagramBlockEntry, AsciiDiagramExtension, type AsciiDiagramExtensionOptions, type AsciiDiagramPluginState, type AsciiDiagramView, AsciiDiagramWidget, BlockCardView, type BlockCardViewProps, type BlockNavigator, BlockPropertiesPopover, type BlockPropertiesPopoverProps, type BlockRange, type BlockSlice, type BlockTagVisibility, CODE_SNIPPET_KEY, CODE_SNIPPET_LANGUAGES, type CameraStreamOptions, type CanvasRect, type CanvasSink, type CaptureKind, type CodeContext, type CodeContextSection, CodeContextZones, type CodeSnippetBlockEntry, type CodeSnippetData, CodeSnippetExtension, type CodeSnippetExtensionOptions, type CodeSnippetLanguage, type CodeSnippetPluginState, CodeSnippetWidget, type CodeSnippetWidgetProps, type CustomTemplateContextValue, CustomTemplateProvider, type CustomTemplateProviderProps, type CustomThemeContextValue, CustomThemeProvider, type CustomThemeProviderProps, DEFAULT_MERMAID_DIAGRAM_TYPE, DEFAULT_TELEPROMPTER_PREFS, DiagramCanvas, type DiagramCommand, type DiagramData, type DiagramEdge, type DiagramNode, type DirectionModel, type DocCustomTemplates, type DocCustomThemes, type DocumentLinkCandidate, type DocumentLinkProvider, DocumentSettingsDialog, type DocumentSettingsDialogProps, type DragContentType, type DropTarget, DropZoneOverlay, type DropZoneOverlayProps, EMPTY_TRANSITION, EYE_LINE_FRACTION, type EditorActions, type EditorColorScheme, type EditorContextValue, type EditorMode, EditorProvider, type EditorProviderProps, EditorShell, type EditorShellProps, type EditorState, type EditorView, EmojiPicker, type EmojiPickerProps, type FileCategory, type FileKind, type FloatOpenOptions, type FloatTier, type FloatingWindowHandle, type FloatingWindowManager, type FolderEntry, FolderView, type FolderViewProps, type HeadingTransitionAttrs, HeadingWithTemplate, type ImageDisplayMode, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, ImportThemeSection, type ImportThemeSectionProps, type ImportedThemeResult, InlinePreviewGutter, type InlinePreviewGutterProps, JsonEditor, type JsonEditorProps, type LayoutMode, MERMAID_DIAGRAM_KEY, MERMAID_DIAGRAM_TYPES, MERMAID_FLOWCHART_SHAPES, MediaBin, type MediaBinProps, type MediaClipPatch, type MentionCandidate, type MentionProvider, type MermaidDiagramBlockEntry, MermaidDiagramCanvas, type MermaidDiagramCanvasProps, type MermaidDiagramCategory, type MermaidDiagramData, MermaidDiagramExtension, type MermaidDiagramExtensionOptions, type MermaidDiagramPluginState, type MermaidDiagramPreview, type MermaidDiagramType, MermaidDiagramTypeThumbnail, MermaidDiagramWidget, type MermaidDiagramWidgetProps, type MermaidEditableEdge, type MermaidEditableModel, type MermaidEditableNode, type MermaidFlowchartDirection, type MermaidFlowchartModel, type MermaidFlowchartShape, type MermaidFlowchartShapeId, type MermaidNodeCanvasAction, type MermaidRenderResult, MermaidShapePalette, type MermaidShapePaletteProps, type MicAnalysisHandle, type MicAnalysisStatus, type MonacoWorkerConstructor, type MonacoWorkerConstructors, type NarrationRecorderController, type NarrationRecorderState, type NarrationSavePlan, type NarrationSaveResult, type NarrationTake, OutlinePanel, type OutlinePanelProps, PCM_WORKLET_NAME, PCM_WORKLET_SOURCE, PICKER_CATEGORIES, type PickerCategory, type PickerEntry, PlainHtmlPreview, type PlainHtmlPreviewProps, PreviewFormatSwitch, PreviewModeMenu, PreviewModeSwitch, PreviewPanel, type PreviewPanelProps, type PreviewSettings, PreviewSettingsProvider, PreviewToolbarControls, type PrompterTransport, REPAIRABLE_KEY, RawEditor, type RawEditorProps, type RecordedBookmark, RecorderButton, type RecorderButtonProps, type RecorderColorScheme, RecorderModal, type RecorderModalProps, RecorderPanel, type RecorderPanelProps, type RecorderSaveResult, type RecorderSource, type RecorderState, type RepairableBlockEntry, RepairableDiagramExtension, type RepairableDiagramExtensionOptions, type RepairablePluginState, type ResolvedFormat, type ScreenStreamHandle, type ScreenStreamOptions, StatusBar, type StatusBarProps, TELEPROMPTER_CSS, TIMELINE_VIEW_KEY, TRANSITION_ENTRIES, TRANSITION_GROUPS, type TeleprompterController, TeleprompterControls, type TeleprompterControlsProps, type TeleprompterPrefs, type TeleprompterRecordingDeps, TeleprompterSurface, type TeleprompterSurfaceProps, TeleprompterView, type TeleprompterViewProps, TemplatePicker, ThemeCustomizerPanel, type ThemeCustomizerPanelProps, type ThemeInheritance, ThemePicker, type ThemePickerProps, type ThemeSaveExtras, type TimelineBlockEntry, type TimelineCommand, type TimelineCommandResult, TimelineEditorWidget, type TimelineEditorWidgetProps, type TimelineEventPatch, TimelineTrack, type TimelineTrackProps, type TimelineViewData, TimelineViewExtension, type TimelineViewExtensionOptions, type TimelineViewPluginState, type TimingJson, type TokenLineMap, Toolbar, type ToolbarProps, TooltipLayer, type TransitionCatalogEntry, type TransitionFields, type TransitionGroup, TransitionPicker, type TransitionPickerProps, type TreeBlockEntry, type TreeCommand, TreeOutlineWidget, type TreeViewData, TreeViewExtension, type TreeViewExtensionOptions, type TreeViewPluginState, type UseBlockNavigatorOptions, type UseFileDropOptions, type UseFileDropResult, type UseImageEditorOptions, type UseImageEditorReturn, type UseMediaRecorderOptions, type UseMediaRecorderResult, type UseMonacoLoaderResult, VersionHistoryPanel, ViewMenuPanel, type ViewPreferences, ViewSwitcher, type ViewSwitcherProps, type WriteCanvasSettings, WysiwygEditor, type WysiwygEditorProps, addEdgeOp, addItemOp, addNodeOp, addTimelineEventOp, applyAsciiDiagramCommand, applyRepairCommand, applyTimelineCommand, applyTreeCommand, asciiDiagramToCanvas, buildFilename, buildNarrationSavePlan, buildPreviewDoc, buildTimingJson, cameraVideoLine, classifyFile, codeSnippetFenceLanguageToken, codeSnippetLanguageLabel, codeSnippetMarkdown, configureMonacoWorkers, createFloatingWindowManager, detectFloatTiers, detectLanguageFromFileName, draftPatchFromImportedTheme, encodeTimingJson, ensureTeleprompterStyles, executeNarrationSave, findAsciiDiagramBlockPos, findCodeSnippetBlockPos, findMermaidDiagramBlockPos, findRepairableBlockPos, findTimelineBlockPos, findTransitionEntry, findTreeBlockPos, formatSeconds, getBlockSlices, getCaptureKind, getTimelineForNode, imageEditorReducer, indentItemOp, initialImageEditorState, insertNarrationPreamble, inspectMermaidSource, isAsciiSourceVisible, isCodeSnippetFenceLanguage, isCodeSnippetNode, isMermaidDiagramNode, isMermaidFlowchartShapeId, isMermaidSourceVisible, isRepairableFence, isTimelineSourceSafeForSemanticEdit, lineToOffset, markdownToTiptap, measureTokenLines, mermaidDiagramMarkdown, mermaidErrorMessage, monacoLanguageForFence, moveItemDownOp, moveItemUpOp, moveNodeOp, narrationAnnotationLine, nextTimelineEventId, normalizeMermaidFlowchartShape, offsetToLine, outdentItemOp, parseTimelineForNode, partitionFiles, processMediaFiles, processTextFile, processTextFiles, prompterVarsFromTheme, readBlockAttrsParams, readBlockAttrsTransition, readBlockAttrsValue, readHeadingLineTransition, registerPcmWorklet, removeEdgeOp, removeItemOp, removeNodeOp, removeTimelineEventOp, renameItemOp, renameNodeOp, renderMermaidDiagram, replaceAsciiFenceText, replaceCodeSnippetText, replaceAsciiFenceText as replaceTreeFenceText, requestCameraStream, requestMicStream, requestScreenStream, resizeNodeOp, resolveFileKind, resolveFormat, sanitizeAsciiLabel, sanitizeTimelineText, sanitizeTreeLabel, searchPickerEntries, setBlockAttrsValue, setBlockDurationInSource, setHeadingAttrsTransition, setHeadingLineTransition, setMediaClipInSource, shouldPasteAsAsciiFence, shouldPasteAsTimelineFence, shouldPasteAsTreeFence, sliceIndexAtOffset, spliceBlock, stepScroll, summarizeBlockProps, supportsDisplayMedia, supportsMediaRecorder, supportsUserMedia, targetOffsetFor, templateLabel, timingPathFor, tiptapToMarkdown, toggleAsciiSource, toggleDirOp, toggleMermaidSource, transitionLabel, translateDiagramOp, updateTimelineEventOp, useAsciiDiagramData, useBlockNavigator, useCodeSnippetData, useCustomTemplates, useCustomThemes, useDocCustomTemplates, useDocCustomThemes, useEditorContext, useFileDrop, useFloatingWindow, useImageEditor, useMediaRecorder, useMermaidDiagramData, useMicAnalysis, useMonacoLoader, useNarrationRecorder, usePreviewSettings, useStreamPreview, useTeleprompter, useTimelineData, useTreeViewData, vadConfigForSensitivity };
+export { ALL_PICKER_ENTRIES, type AddTimelineEventOptions, type AddTimelineEventResult, type ApplyAsciiDiagramCommandOptions, type AsciiDiagramBlockEntry, AsciiDiagramExtension, type AsciiDiagramExtensionOptions, type AsciiDiagramPluginState, type AsciiDiagramView, AsciiDiagramWidget, BlockCardView, type BlockCardViewProps, type BlockNavigator, BlockPropertiesPopover, type BlockPropertiesPopoverProps, type BlockRange, type BlockSlice, type BlockTagVisibility, CODE_SNIPPET_KEY, CODE_SNIPPET_LANGUAGES, type CameraStreamOptions, type CanvasRect, type CanvasSink, type CaptureKind, type CodeContext, type CodeContextSection, CodeContextZones, type CodeSnippetBlockEntry, type CodeSnippetData, CodeSnippetExtension, type CodeSnippetExtensionOptions, type CodeSnippetLanguage, type CodeSnippetPluginState, CodeSnippetWidget, type CodeSnippetWidgetProps, type CustomTemplateContextValue, CustomTemplateProvider, type CustomTemplateProviderProps, type CustomThemeContextValue, CustomThemeProvider, type CustomThemeProviderProps, DEFAULT_MERMAID_DIAGRAM_TYPE, DEFAULT_TELEPROMPTER_PREFS, DiagramCanvas, type DiagramCommand, type DiagramData, type DiagramEdge, type DiagramNode, type DirectionModel, type DocCustomTemplates, type DocCustomThemes, type DocumentLinkCandidate, type DocumentLinkProvider, DocumentSettingsDialog, type DocumentSettingsDialogProps, type DragContentType, type DropTarget, DropZoneOverlay, type DropZoneOverlayProps, EMPTY_TRANSITION, EYE_LINE_FRACTION, type EditorActions, type EditorColorScheme, type EditorContextValue, type EditorMode, EditorProvider, type EditorProviderProps, EditorShell, type EditorShellProps, type EditorState, type EditorView, EmojiPicker, type EmojiPickerProps, type FileCategory, type FileKind, type FloatOpenOptions, type FloatTier, type FloatingWindowHandle, type FloatingWindowManager, type FolderEntry, FolderView, type FolderViewProps, type HeadingTransitionAttrs, HeadingWithTemplate, type ImageDisplayMode, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, ImportThemeSection, type ImportThemeSectionProps, type ImportedThemeResult, InlinePreviewGutter, type InlinePreviewGutterProps, JsonEditor, type JsonEditorProps, type LayoutMode, MERMAID_DIAGRAM_KEY, MERMAID_DIAGRAM_TYPES, MERMAID_FLOWCHART_SHAPES, MediaBin, type MediaBinProps, type MediaClipPatch, type MentionCandidate, type MentionProvider, type MermaidDiagramBlockEntry, MermaidDiagramCanvas, type MermaidDiagramCanvasProps, type MermaidDiagramCategory, type MermaidDiagramData, MermaidDiagramExtension, type MermaidDiagramExtensionOptions, type MermaidDiagramPluginState, type MermaidDiagramPreview, type MermaidDiagramProperty, type MermaidDiagramType, MermaidDiagramTypeThumbnail, MermaidDiagramWidget, type MermaidDiagramWidgetProps, type MermaidEditCapabilities, type MermaidEditableDiagramKind, type MermaidEditableEdge, type MermaidEditableModel, type MermaidEditableNode, type MermaidFlowchartDirection, type MermaidFlowchartModel, type MermaidFlowchartShape, type MermaidFlowchartShapeId, type MermaidNodeCanvasAction, type MermaidRenderResult, MermaidShapePalette, type MermaidShapePaletteProps, type MermaidSourceEditableModel, type MicAnalysisHandle, type MicAnalysisStatus, type MonacoWorkerConstructor, type MonacoWorkerConstructors, type NarrationRecorderController, type NarrationRecorderState, type NarrationSavePlan, type NarrationSaveResult, type NarrationTake, OutlinePanel, type OutlinePanelProps, PCM_WORKLET_NAME, PCM_WORKLET_SOURCE, PICKER_CATEGORIES, type PickerCategory, type PickerEntry, PlainHtmlPreview, type PlainHtmlPreviewProps, PreviewFormatSwitch, PreviewModeMenu, PreviewModeSwitch, PreviewPanel, type PreviewPanelProps, type PreviewSettings, PreviewSettingsProvider, PreviewToolbarControls, type PrompterTransport, REPAIRABLE_KEY, RawEditor, type RawEditorProps, type RecordedBookmark, RecorderButton, type RecorderButtonProps, type RecorderColorScheme, RecorderModal, type RecorderModalProps, RecorderPanel, type RecorderPanelProps, type RecorderSaveResult, type RecorderSource, type RecorderState, type RepairableBlockEntry, RepairableDiagramExtension, type RepairableDiagramExtensionOptions, type RepairablePluginState, type ResolvedFormat, type ScreenStreamHandle, type ScreenStreamOptions, StatusBar, type StatusBarProps, TELEPROMPTER_CSS, TIMELINE_VIEW_KEY, TRANSITION_ENTRIES, TRANSITION_GROUPS, type TeleprompterController, TeleprompterControls, type TeleprompterControlsProps, type TeleprompterPrefs, type TeleprompterRecordingDeps, TeleprompterSurface, type TeleprompterSurfaceProps, TeleprompterView, type TeleprompterViewProps, TemplatePicker, ThemeCustomizerPanel, type ThemeCustomizerPanelProps, type ThemeInheritance, ThemePicker, type ThemePickerProps, type ThemeSaveExtras, type TimelineBlockEntry, type TimelineCommand, type TimelineCommandResult, TimelineEditorWidget, type TimelineEditorWidgetProps, type TimelineEventPatch, TimelineTrack, type TimelineTrackProps, type TimelineViewData, TimelineViewExtension, type TimelineViewExtensionOptions, type TimelineViewPluginState, type TimingJson, type TokenLineMap, Toolbar, type ToolbarProps, TooltipLayer, type TransitionCatalogEntry, type TransitionFields, type TransitionGroup, TransitionPicker, type TransitionPickerProps, type TreeBlockEntry, type TreeCommand, TreeOutlineWidget, type TreeViewData, TreeViewExtension, type TreeViewExtensionOptions, type TreeViewPluginState, type UseBlockNavigatorOptions, type UseFileDropOptions, type UseFileDropResult, type UseImageEditorOptions, type UseImageEditorReturn, type UseMediaRecorderOptions, type UseMediaRecorderResult, type UseMonacoLoaderResult, VersionHistoryPanel, ViewMenuPanel, type ViewPreferences, ViewSwitcher, type ViewSwitcherProps, type WriteCanvasSettings, WysiwygEditor, type WysiwygEditorProps, addEdgeOp, addItemOp, addNodeOp, addTimelineEventOp, applyAsciiDiagramCommand, applyRepairCommand, applyTimelineCommand, applyTreeCommand, asciiDiagramToCanvas, buildFilename, buildNarrationSavePlan, buildPreviewDoc, buildTimingJson, cameraVideoLine, classifyFile, codeSnippetFenceLanguageToken, codeSnippetLanguageLabel, codeSnippetMarkdown, configureMonacoWorkers, createFloatingWindowManager, detectFloatTiers, detectLanguageFromFileName, draftPatchFromImportedTheme, encodeTimingJson, ensureTeleprompterStyles, executeNarrationSave, findAsciiDiagramBlockPos, findCodeSnippetBlockPos, findMermaidDiagramBlockPos, findRepairableBlockPos, findTimelineBlockPos, findTransitionEntry, findTreeBlockPos, formatSeconds, getBlockSlices, getCaptureKind, getTimelineForNode, imageEditorReducer, indentItemOp, initialImageEditorState, insertNarrationPreamble, inspectMermaidSource, isAsciiSourceVisible, isCodeSnippetFenceLanguage, isCodeSnippetNode, isMermaidDiagramNode, isMermaidFlowchartShapeId, isMermaidSourceVisible, isRepairableFence, isTimelineSourceSafeForSemanticEdit, lineToOffset, markdownToTiptap, measureTokenLines, mermaidDiagramMarkdown, mermaidDiagramProperties, mermaidEditCapabilities, mermaidErrorMessage, monacoLanguageForFence, moveItemDownOp, moveItemUpOp, moveNodeOp, narrationAnnotationLine, nextTimelineEventId, normalizeMermaidFlowchartShape, offsetToLine, outdentItemOp, parseTimelineForNode, partitionFiles, processMediaFiles, processTextFile, processTextFiles, prompterVarsFromTheme, readBlockAttrsParams, readBlockAttrsTransition, readBlockAttrsValue, readHeadingLineTransition, registerPcmWorklet, removeEdgeOp, removeItemOp, removeNodeOp, removeTimelineEventOp, renameItemOp, renameNodeOp, renderMermaidDiagram, replaceAsciiFenceText, replaceCodeSnippetText, replaceAsciiFenceText as replaceTreeFenceText, requestCameraStream, requestMicStream, requestScreenStream, resizeNodeOp, resolveFileKind, resolveFormat, sanitizeAsciiLabel, sanitizeTimelineText, sanitizeTreeLabel, searchPickerEntries, setBlockAttrsValue, setBlockDurationInSource, setHeadingAttrsTransition, setHeadingLineTransition, setMediaClipInSource, shouldPasteAsAsciiFence, shouldPasteAsTimelineFence, shouldPasteAsTreeFence, sliceIndexAtOffset, spliceBlock, stepScroll, summarizeBlockProps, supportsDisplayMedia, supportsMediaRecorder, supportsUserMedia, targetOffsetFor, templateLabel, timingPathFor, tiptapToMarkdown, toggleAsciiSource, toggleDirOp, toggleMermaidSource, transitionLabel, translateDiagramOp, updateTimelineEventOp, useAsciiDiagramData, useBlockNavigator, useCodeSnippetData, useCustomTemplates, useCustomThemes, useDocCustomTemplates, useDocCustomThemes, useEditorContext, useFileDrop, useFloatingWindow, useImageEditor, useMediaRecorder, useMermaidDiagramData, useMicAnalysis, useMonacoLoader, useNarrationRecorder, usePreviewSettings, useStreamPreview, useTeleprompter, useTimelineData, useTreeViewData, vadConfigForSensitivity };